home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / appicon.doc next >
Encoding:
Text File  |  1998-10-26  |  17.0 KB  |  504 lines
  1. dopus5.library/AppXXX routines                 dopus5.library/AppXXX routines
  2.  
  3.     The dopus5.library installs patches into the system when it loads to
  4.     intercept calls to the workbench.library AddAppXXX() functions. This
  5.     allows DOpus to show AppIcons, AppMenuItems, and support drag and drop
  6.     onto AppWindows.
  7.  
  8.     The emulation is transparent as far as a third-party application is
  9.     concerned, but it is possible to access additional features that DOpus
  10.     provides (especially for AppIcons). Obviously these are only available
  11.     through DOpus, and not through Workbench.
  12.  
  13.     Using tags with the AddAppIcon() function, it is possible to control
  14.     the DOpus-only features of AppIcons. Workbench ignores these tags, and
  15.     so if Workbench is running as well it will just see the plain AppIcon
  16.     itself.
  17.  
  18.     The tags are as follows :
  19.  
  20.         DAE_Local
  21.  
  22.         This tag causes the icon to only be added to DOpus. If Workbench is
  23.         running as well, it will not see this icon. Supplying this tag
  24.         is probably a good idea if your AppIcon depends on some of the other
  25.         DOpus-specific functions.
  26.  
  27.         DAE_Snapshot
  28.  
  29.         Indicates that this icon can support the Snapshot function. If this
  30.         tag is specified, the Snapshot item in the icon popup menu will be
  31.         enabled, and the Snapshot item in the main Icon menu will work.
  32.         Use of this tag generates AppSnapshotMsgs, see below for more
  33.         information.
  34.  
  35.         DAE_Close
  36.  
  37.         Turns the 'Open' item in the icon popup menu into a 'Close' item.
  38.         APPSNAPF_CLOSE will be set in the AppSnapshotMsg that is
  39.         generated.
  40.  
  41.         DAE_Info
  42.  
  43.         Indicates that this icon can support the Information function.
  44.         This is similar in operation to the DAE_Snapshot tag. The
  45.         APPSNAPF_INFO flag will be set in the AppSnapshotMsg.
  46.  
  47.         DAE_Menu
  48.  
  49.         This tag can be used several times for one icon. It allows you to
  50.         specify additional entries for the icon popup menu. ti_Data points
  51.         to a string that is displayed for the menu item. The order these
  52.         tags are supplied specifies the order they are displayed, and
  53.         also controls the ID that is returned in AppSnapshotMsgs.
  54.  
  55.         DAE_ToggleMenu
  56.  
  57.         Similar to DAE_Menu, this allows you to specify a menu item for
  58.         the icon popup menu. The only difference is that the menu item
  59.         is a toggle-select item (analagous to CHECKIT for Intuition menus).
  60.  
  61.         DAE_ToggleMenuSel
  62.  
  63.         The same as DAE_ToggleMenu, but specifies that the item is to be
  64.         selected by default (analagous to CHECKED for Intuition menus).
  65.  
  66.         DAE_MenuBase
  67.  
  68.         This tag allows you to specify a base ID for menu IDs that
  69.         are generated via the DAE_Menu, DAE_ToggleMenu and DAE_ToggleMenuSel
  70.         tags. Menu IDs usually start at 0 for the first menu and increase
  71.         from there. If you specify the DAE_MenuBase tag, the menu IDs will
  72.         start from your supplied value.
  73.  
  74.         DAE_Background
  75.  
  76.         This allows you to specify a pen to use to render the background
  77.         colour of the icon. If not supplied, the default is pen 0.
  78.  
  79.         DAE_Locked
  80.  
  81.         This tag specifies that the icon position is to be locked.
  82.         That is, the user will be unable to reposition the icon from the
  83.         initial coordinates. This flag can be changed later using the
  84.         ChangeAppIcon() function.
  85.  
  86.  
  87.     Using the new tags can cause special messages to be sent to your
  88.     message port. These are an extension of the normal AppMessages,
  89.     and can be identified by an am_Type of MTYPE_APPSNAPSHOT.
  90.  
  91.     The events you will get special messages for are :
  92.  
  93.         Snapshot
  94.  
  95.         If the DAE_Snapshot tag was specified and the user snapshots your
  96.         icon, you will receive a message containing the icon position
  97.         (AppSnapshotMsg->position_x and AppSnapshotMsg->position_y).
  98.         It is your responsibility to save these values, and use them
  99.         when adding the AppIcon in the future.
  100.  
  101.         If the APPSNAPF_WINDOW_POS flag is set in the AppSnapshotMsg->flags
  102.         field, the position in AppSnapshotMsg->window_pos is also valid.
  103.  
  104.         Un-Snapshot
  105.  
  106.         If the DAE_Snapshot tag was specified and the user unsnapshots
  107.         your icon, you will receive a message with the APPSNAPF_UNSNAPSHOT
  108.         flag set.
  109.  
  110.         Close
  111.  
  112.         If DAE_Close was specified, and the user selects the Close item
  113.         in the icon popup menu, you will receive a message with the
  114.         APPSNAPF_CLOSE flag set.
  115.  
  116.         Information
  117.  
  118.         You will receive a message with the APPSNAPF_INFO flag set if you
  119.         specified the DAE_Info tag, and the user selects Information on your
  120.         icon.
  121.  
  122.         Menu
  123.  
  124.         If menus were added with the DAE_Menu tags, you will receive a
  125.         message with the APPSNAPF_MENU flag set when the user selects one
  126.         of your menu items. The AppSnapshotMsg->id field contains the
  127.         item ID. If the user pressed the help key on one of the items,
  128.         the APPSNAPF_HELP flag will also be set.
  129.  
  130.     Directory Opus also sends additional information to AppWindows. If you
  131.     receive an AppMessage of type MTYPE_APPWINDOW, you should check to see
  132.     if it is an Opus message using the CheckAppMessage() function. If so,
  133.     the message is a DOpusAppMessage, which contains additional information.
  134.     The extra fields are :
  135.  
  136.         da_DropPos
  137.  
  138.         This field contains an array of Point structures. Each structure
  139.         gives the offset from the origin of each file in the message.
  140.         This allows you to maintain the relative positions of all icons
  141.         dropped in a multiple-file operation.
  142.  
  143.         da_DragOffset
  144.  
  145.         This Point structure gives you the offset of the primary icon
  146.         from the mouse pointer. That is, if the user clicked on the primary
  147.         icon in the top-left corner, this offset would be 0,0. If they
  148.         picked up the icon from the bottom-right corner, it might be 32,18.
  149.  
  150.         da_Flags
  151.  
  152.         The only flag supported so far is DAPPF_ICON_DROP. This indicates
  153.         that the files dropped were in fact icons (ie from an icon mode
  154.         lister).
  155.  
  156.     The da_DropPos and da_DragOffset fields enable you to calculate the
  157.     exact position that the user dropped the files on. Normal AppMessages
  158.     only provide the position of the mouse pointer, which is useless if you
  159.     want to maintain the relative and correct positions of the icons.
  160.  
  161. dopus5.library/AllocAppMessage                 dopus5.library/AllocAppMessage
  162.  
  163.     NAME
  164.         AllocAppMessage - allocate a DOpusAppMessage
  165.  
  166.     SYNOPSIS
  167.         AllocAppMessage(memory, port, count)
  168.                           A0     A1     D0
  169.  
  170.         DOpusAppMessage *AllocAppMessage(APTR, struct MsgPort *, short);
  171.  
  172.     FUNCTION
  173.         This function allows you to create a DOpusAppMessage (an extended
  174.         AppMessage) easily.
  175.  
  176.     INPUTS
  177.         memory - memory handle or NULL (see memory.doc)
  178.         port - address of reply port
  179.         count - number of arguments
  180.  
  181.     RESULT
  182.         Allocates a DOpusAppMessage, including space for count arguments
  183.         (both da_Msg.am_ArgList and da_DropPos will be initialised).
  184.  
  185.     NOTES
  186.         Unless you actually want to send an AppMessage to a DOpus window
  187.         with relative icon positions, you don't really need this function.
  188.         It does provide a convenient way to allocate an AppMessage, though,
  189.         and there's no reason you can't use DOpusAppMessages totally in
  190.         place of AppMessages if you want to.
  191.  
  192.     SEE ALSO
  193.         FreeAppMessage(), SetWBArg()
  194.  
  195. dopus5.library/AppWindowData                     dopus5.library/AppWindowData
  196.  
  197.     NAME
  198.         AppWindowData - extract data from an AppWindow
  199.  
  200.     SYNOPSIS
  201.         AppWindowData(appwindow, idptr, userdataptr)
  202.                          A0        A1       A2
  203.  
  204.         struct MsgPort *AppWindowData(APTR, ULONG *, ULONG *);
  205.  
  206.     FUNCTION
  207.         This function returns the ID, Userdata and Message port associated
  208.         with the specified AppWindow. These are the parameters that are
  209.         supplied in the call to AddAppWindow.
  210.  
  211.     INPUTS
  212.         appwindow - AppWindow handle
  213.         idptr - pointer to ULONG to contain the ID
  214.         userdataptr - pointer to ULONG to contain the Userdata
  215.  
  216.     RESULT
  217.         The AppWindow ID and Userdata are stored in the variables supplied,
  218.         and the address of the AppWindow's message port is returned.
  219.  
  220.     SEE ALSO
  221.         FindAppWindow(), workbench.library/AddAppWindow()
  222.  
  223. dopus5.library/AppWindowWindow                 dopus5.library/AppWindowWindow
  224.  
  225.     NAME
  226.         AppWindowWindow - get Window pointer from an AppWindow
  227.  
  228.     SYNOPSIS
  229.         AppWindowWindow(appwindow)
  230.                            A0
  231.  
  232.         struct Window *AppWindowWindow(APTR);
  233.  
  234.     FUNCTION
  235.         This function returns the underlying Window pointer for the
  236.         specified AppWindow.
  237.  
  238.     INPUTS
  239.         appwindow - AppWindow handle
  240.  
  241.     RESULT
  242.         The Window pointer is returned.
  243.  
  244.     SEE ALSO
  245.         FindAppWindow(), workbench.library/AddAppWindow()
  246.  
  247. dopus5.library/ChangeAppIcon                     dopus5.library/ChangeAppIcon
  248.  
  249.     NAME
  250.         ChangeAppIcon - make changes to an AppIcon
  251.  
  252.     SYNOPSIS
  253.         ChangeAppIcon(icon, render, select, label, flags)
  254.                        A0     A1      A2      A3     D0
  255.  
  256.         void ChangeAppIcon
  257.              (APTR, struct Image *, struct Image *, char *,
  258.               ULONG);
  259.  
  260.     FUNCTION
  261.         This function allows you to make changes to an AppIcon that
  262.         was previously added to DOpus. It has no effect on the icon
  263.         on Workbench, so you should use the DAE_Local tag when adding
  264.         the icon if your program depends on this function.
  265.  
  266.         You are able to change both frames of the icon's image and the
  267.         icon's label. You can also lock or unlock the icon's position,
  268.         and make it busy.
  269.  
  270.     INPUTS
  271.         icon - icon to act on, as returned by AddAppIcon()
  272.         render - new main image for the icon
  273.         select - new select image for the icon
  274.         label - new label for the icon
  275.         flags - control flags. The available flags are :
  276.  
  277.                 CAIF_RENDER     - change the main image
  278.                 CAIF_SELECT     - change the select image
  279.                 CAIF_TITLE      - change the label
  280.                 CAIF_LOCKED     - change the 'locked' flag
  281.                 CAIF_SET        - use with CAIF_LOCKED
  282.                 CAIF_BUSY       - make icon busy
  283.                 CAIF_UNBUSY     - make icon unbusy
  284.  
  285.     NOTES
  286.         To lock an icon, pass CAIF_LOCKED|CAIF_SET. To unlock it, pass
  287.         CAIF_LOCKED by itself. The render, select and label parameters are
  288.         ignored unless their corresponding flags are set. You can specify
  289.         any combination of these flags at once. To reduce the visible
  290.         effects, you should make as many changes with the one call as
  291.         possible.
  292.  
  293.     SEE ALSO
  294.         SetAppIconMenuState(), workbench.library/AddAppIcon
  295.  
  296. dopus5.library/CheckAppMessage                 dopus5.library/CheckAppMessage
  297.  
  298.     NAME
  299.         CheckAppMessage - check if an AppMessage is from DOpus
  300.  
  301.     SYNOPSIS
  302.         CheckAppMessage(msg)
  303.                          A0
  304.  
  305.         BOOL CheckAppMessage(DOpusAppMessage *);
  306.  
  307.     FUNCTION
  308.         This function allows you to discover whether an AppMessage is
  309.         actually an extended DOpusAppMessage.
  310.  
  311.     INPUTS
  312.         msg - AppMessage to test
  313.  
  314.     RESULT
  315.         Returns TRUE if the message is a DOpusAppMessage.
  316.  
  317.     NOTES
  318.         You MUST only pass AppMessages (or DOpusAppMessages) to this
  319.         function. Passing other types of messages (eg IntuiMessages)
  320.         results in undefined behaviour.
  321.  
  322.     SEE ALSO
  323.         AllocAppMessage()
  324.  
  325. dopus5.library/FindAppWindow                     dopus5.library/FindAppWindow
  326.  
  327.     NAME
  328.         FindAppWindow - test to see if a window is an AppWindow
  329.  
  330.     SYNOPSIS
  331.         FindAppWindow(window)
  332.                         A0
  333.  
  334.         APTR FindAppWindow(struct Window *);
  335.  
  336.     FUNCTION
  337.         This routine allows you to discover whether a Window is in fact
  338.         an AppWindow.
  339.  
  340.     INPUTS
  341.         window - pointer to the window to test
  342.  
  343.     RESULT
  344.         Returns the AppWindow handle if it is an AppWindow, or NULL if not.
  345.  
  346.     NOTES
  347.         You should only use the returned value within a Forbid()/Permit(),
  348.         as the window in question could disappear at any time. Also note that
  349.         the system patches are not installed until the dopus5.library is
  350.         loaded. Any AppWindows added to the system before the patches are
  351.         installed are undetectable.
  352.  
  353.     SEE ALSO
  354.         AppWindowData(), workbench.library/AddAppWindow()
  355.  
  356. dopus5.library/FreeAppMessage                   dopus5.library/FreeAppMessage
  357.  
  358.     NAME
  359.         FreeAppMessage - frees a DOpusAppMessage
  360.  
  361.     SYNOPSIS
  362.         FreeAppMessage(msg)
  363.                         A0
  364.  
  365.         void FreeAppMessage(DOpusAppMessage *);
  366.  
  367.     FUNCTION
  368.         This function frees the supplied DOpusAppMessage. It is only
  369.         designed for messages allocated with AllocAppMessage.
  370.  
  371.     INPUTS
  372.         msg - message to free
  373.  
  374.     NOTES
  375.         You should not use this routine for AppMessages you receive
  376.         (ie are sent by another process). You should ReplyMsg() those
  377.         messages as normal. This function is used to free DOpusAppMessages
  378.         that YOU create, usually when they are replied to by another
  379.         task.
  380.  
  381.     SEE ALSO
  382.         AllocAppMessage()
  383.  
  384. dopus5.library/GetWBArgPath                       dopus5.library/GetWBArgPath
  385.  
  386.     NAME
  387.         GetWBArgPath - extract pathname from WBArg
  388.  
  389.     SYNOPSIS
  390.         GetWBArgPath(wbarg, buffer, size)
  391.                       A0      A1     D0
  392.  
  393.         BOOL GetWBArgPath(struct WBArg *, char *, long);
  394.  
  395.     FUNCTION
  396.         This function is provided as a convenient method of extracting
  397.         the pathname of a file/directory from a WBArg structure (usually
  398.         within an AppMessage).
  399.  
  400.     INPUTS
  401.         wbarg - pointer to the WBArg structure
  402.         buffer - buffer to write pathname to
  403.         size - size of buffer
  404.  
  405.     RESULT
  406.         The full path and name of the object referred to by the WBArg
  407.         structure is copied to the supplied buffer. This routine returns
  408.         TRUE if it was successful.
  409.  
  410. dopus5.library/ReplyAppMessage                 dopus5.library/ReplyAppMessage
  411.  
  412.     NAME
  413.         ReplyAppMessage - reply to an AppMessage
  414.  
  415.     SYNOPSIS
  416.         ReplyAppMessage(msg)
  417.                          A0
  418.  
  419.         void ReplyAppMessage(DOpusAppMessage *);
  420.  
  421.     FUNCTION
  422.         This function is the best way to reply to a DOpusAppMessage. Its
  423.         operation is quite straightforward - if the message has a reply
  424.         port set, it calls ReplyMsg() as normal. Otherwise, it calls
  425.         FreeAppMessage. This allows messages to be sent with no reply
  426.         needed. Directory Opus will never send an AppMessage without a
  427.         reply port, but you might want to use this routine among your
  428.         own processes.
  429.  
  430.     INPUTS
  431.         msg - message to reply to
  432.  
  433.     RESULT
  434.         The message is replied or freed.
  435.  
  436.     SEE ALSO
  437.         FreeAppMessage()
  438.  
  439. dopus5.library/SetAppIconMenuState         dopus5.library/SetAppIconMenuState
  440.  
  441.     NAME
  442.         SetAppIconMenuState - change the state of an icon popup menu
  443.  
  444.     SYNOPSIS
  445.         SetAppIconMenuState(icon, item, state)
  446.                              A0    D0     D1
  447.  
  448.         long SetAppIconMenuState(APTR, long, long);
  449.  
  450.     FUNCTION
  451.         This allows you to set the state of a toggle-select menu item in
  452.         the icon popup menu of AppIcons. These menu items would have been
  453.         added with the DAE_ToggleMenu and DAE_ToggleMenuSel tags.
  454.  
  455.     INPUTS
  456.         icon - icon to act on, as returned by AddAppIcon()
  457.         item - number of item to change (in the order they were added)
  458.         state - new state for the item (TRUE=selected)
  459.  
  460.     RESULT
  461.         Returns the old selection state of the item.
  462.  
  463.     NOTES
  464.         This routine uses 0 as a base ID for the menu items, even if you
  465.         specified a new base with DAE_MenuBase.
  466.  
  467.     SEE ALSO
  468.         ChangeAppIcon(), workbench.library/AddAppIcon
  469.  
  470. dopus5.library/SetWBArg                               dopus5.library/SetWBArg
  471.  
  472.     NAME
  473.         SetWBArg - fill out a WBArg entry in a DOpusAppMessage
  474.  
  475.     SYNOPSIS
  476.         SetWBArg(msg, item, lock, name, memory)
  477.                   A0   D0    D1    A1     A2
  478.  
  479.         BOOL SetWBArg(DOpusAppMessage *, short, BPTR, char *, APTR);
  480.  
  481.     FUNCTION
  482.         This routine makes it easy to initialise the WBArg structures
  483.         in an AppMessage (or a DOpusAppMessage).
  484.  
  485.     INPUTS
  486.         msg - AppMessage to initialise
  487.         item - item to initialise (starting at 0)
  488.         lock - lock on parent directory
  489.         name - name of file
  490.         memory - memory handle or NULL
  491.  
  492.     RESULT
  493.         The specified WBArg in the AppMessage is initialised with the
  494.         lock and name specified. This routine returns TRUE if it was
  495.         successful.
  496.  
  497.     NOTES
  498.         'lock' is the lock of the item's parent directory in the case of
  499.         files, or on the item itself in the case of directories. For files,
  500.         'name' is the name of the file. 'name' is null for directories.
  501.         The lock and name you supply are both copied, so they do not need
  502.         to remain valid once this call is complete.
  503.  
  504.